Skip to main content

Authentication API

Below is a guide to using Keycloak's Authentication API for common tasks such as obtaining tokens, refreshing tokens, and validating tokens.

1. Set Up Tidecloak​

Before using the API, ensure you have a Tidecloak server running and configured:

  • Create a realm.
  • Create a client (e.g., my-client) with the appropriate settings (e.g., confidential access type).
  • Create users and roles.

2. Tidecloak Authentication API Endpoints​

Tidecloak provides a RESTful API for authentication. The base URL for the API is typically:

http://`<Tidecloak-server>`/auth/realms/`<realm>`/protocol/openid-connect

Common Endpoints​

  • Token Endpoint : /token (for obtaining and refreshing tokens)
  • User Info Endpoint : /userinfo (for retrieving user information)
  • Logout Endpoint : /logout (for logging out)
  • Introspection Endpoint : /token/introspect (for validating tokens)

3. Obtain an Access Token​

To authenticate a user, you need to obtain an access token using the /token endpoint.

Request​

  • Method : POST
  • URL : http://<Tidecloak-server>/auth/realms/<realm>/protocol/openid-connect/token
  • Headers :
  • Content-Type: application/x-www-form-urlencoded
  • Body (form-urlencoded):
    • grant_type: password (for password grant)
    • client_id: Your client ID (e.g., my-client)
    • client_secret: Your client secret (if using confidential client)
    • username: User's username
    • password: User's password

Example​

curl -X POST \
  http://localhost:8080/auth/realms/my-realm/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-client" \
  -d "client_secret=<client-secret>" \
  -d "username=user1" \
  -d "password=password" \
  -d "grant_type=password"

Response​

{
  "access_token": "<access-token>",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "<refresh-token>",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "<session-state>",
  "scope": "profile email"
}

4. Refresh an Access Token​

If the access token expires, you can use the refresh token to obtain a new access token.

Request​

  • Method : POST
  • URL : http://<Tidecloak-server>/auth/realms/<realm>/protocol/openid-connect/token
  • Headers :
  • Content-Type: application/x-www-form-urlencoded
  • Body (form-urlencoded):
    • grant_type: refresh_token
    • client_id: Your client ID
    • client_secret: Your client secret
    • refresh_token: The refresh token from the previous response

Example​

curl -X POST \
  http://localhost:8080/auth/realms/my-realm/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-client" \
  -d "client_secret=<client-secret>" \
  -d "refresh_token=<refresh-token>" \
  -d "grant_type=refresh_token"

Response​

The response will be similar to the initial token response, with a new access token and refresh token.

5. Validate a Token​

To validate an access token, use the /token/introspect endpoint.

Request​

  • Method : POST
  • URL : http://<Tidecloak-server>/auth/realms/<realm>/protocol/openid-connect/token/introspect
  • Headers :
  • Content-Type: application/x-www-form-urlencoded
  • Body (form-urlencoded):
    • client_id: Your client ID
    • client_secret: Your client secret
    • token: The access token to validate

Example​

curl -X POST \
  http://localhost:8080/auth/realms/my-realm/protocol/openid-connect/token/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-client" \
  -d "client_secret=<client-secret>" \
  -d "token=<access-token>"

Response​

{
  "active": true,
  "exp": 1672502400,
  "iat": 1672498800,
  "sub": "<user-id>",
  "username": "user1",
  "email": "user1@example.com"
}

6. Logout​

To log out a user and invalidate their session, use the /logout endpoint.

Request​

  • Method : POST
  • URL : http://<Tidecloak-server>/auth/realms/<realm>/protocol/openid-connect/logout
  • Headers :
  • Content-Type: application/x-www-form-urlencoded
  • Body (form-urlencoded):
    • client_id: Your client ID
    • client_secret: Your client secret
    • refresh_token: The refresh token to invalidate

Example​

curl -X POST \
  http://localhost:8080/auth/realms/my-realm/protocol/openid-connect/logout \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-client" \
  -d "client_secret=<client-secret>" \
  -d "refresh_token=<refresh-token>"

Response​

A successful logout will return a 204 No Content response.

7. Retrieve User Information​

To retrieve user information, use the /userinfo endpoint.

Request​

  • Method : GET
  • URL : http://<Tidecloak-server>/auth/realms/<realm>/protocol/openid-connect/userinfo
  • Headers :
  • Authorization: Bearer <access-token>

Example​

curl -X GET \
  http://localhost:8080/auth/realms/my-realm/protocol/openid-connect/userinfo \
  -H "Authorization: Bearer <access-token>"

Response​

{
  "sub": "<user-id>",
  "email_verified": true,
  "name": "User One",
  "preferred_username": "user1",
  "given_name": "User",
  "family_name": "One",
  "email": "user1@example.com"
}

8. Error Handling​

Tidecloak returns standard HTTP status codes and error messages. For example:

  • 400 Bad Request: Invalid request parameters.
  • 401 Unauthorized: Invalid credentials or token.
  • 403 Forbidden: Insufficient permissions.

Error responses typically include a JSON body with details:

{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}